import { Source, Meta } from '@storybook/blocks';

<Meta title="HOOKS/useEntity" />
# useEntity()
###### `useEntity(entity: string, options?: UseEntityOptions)`
This hook is designed to retrieve an entity and return all it's information including history (if not disabled) and the services for the entity.

This is a memoized wrapper for the getEntity helper from `useHass()` allowing your component to only update
when the entity actually changes.

This hook should be used inside the context of `<HassConnect />` and not outside of it otherwise it will not have access to
the authenticated home assistant API.

<iframe
  style={{
    margin: "auto",
    display: "block",
    marginTop: "20px",
  }}
  width="560"
  height="315"
  frameBorder={0}
  src="https://www.youtube.com/embed/kmNGka8obNA"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
  allowFullScreen
></iframe>



### Example Usage

<Source dark code={`
import { HassConnect, useEntity } from '@hakit/core';
function Office() {
  const lightStrip = useEntity('light.office_striplight');
  // can now access all properties relating to the light
  return lightStrip.state;
}
function App() {
  return <HassConnect hassUrl="http://localhost:1234">
    <Office />
  </HassConnect>
}
`} />

### Options
useEntity takes a second parameter which is an object of options.
The options are:
- `returnNullIfNotFound` - boolean - if true the hook will return null if not found, and not throw an error. Default is false.
- `throttle` - number - how long to wait to throttle the updates, default is 150ms
- `historyOptions` - object - options to pass to receive different history data.

Example:

<Source dark code={`
import { HassConnect, useEntity } from '@hakit/core';
function Office() {
  const lightStrip = useEntity('light.office_striplight', {
    returnNullIfNotFound: true,
    history: {
      disable: false,
      hoursToShow: 96 // defaults to 24
    }
  });
  console.info('light history', lightStrip.history);
  // can now access all properties relating to the light
  return lightStrip?.state ?? 'unknown';
}
function App() {
  return <HassConnect hassUrl="http://localhost:1234">
    <Office />
  </HassConnect>
}
`} />
